註明可能的陷阱

有個寄送電子郵件給指定使用者的函數：

void SendEmail(string to, string subject, string body);

因為函數會連接到外部電子郵件服務，萬一電子郵件服務離線就會造成網頁應用程式「卡住」。
為了避免這種意外，應該註記「實作節細」:

// 呼叫外部服務發送 email (逾時時間為 1 分鐘)
void SendEmail(string to, string subject, string body);

摘要註解

# 找出所有為自己購買商品的客戶
for customer_id in all_customers:
   for sale in all_sales[customer_id].sales:
      if sale.recipient == customer_id:
         ...

對於包含大區塊的長函數而言，這類函數特別有幫助：

def GenerateUserReport():
    #取得使用者的鎖(lock)
    ...
    #從資料庫讀取使用者資訊
    ...
    #將資料寫入檔案
    ...
    #釋放使用者的鎖
    ...

這些註解條列了函數行位摘要，在深入函數運作細節前就能對功能有概念。

Reference

• <<易讀程式之美學－提升程式碼可讀性的簡單法則 >>(The Art of Readable Code)